Quick Start

This guide gets you from zero to a working BindAI application in a few steps. By the end, you will:

Create a BindAI project
Configure an AI provider
Run a BindAI application
Understand the basic project structure
Create an agent
Add tools
Know where to continue next

Prerequisites

Before starting, complete the Installation guide. You should have:

Python 3.11 or newer
BindAI installed
A virtual environment available
Credentials for a supported provider, if required

Current supported providers include:

OpenAI
Anthropic
Google Gemini
Groq
Ollama
OpenRouter

Create a New Project

The BindAI CLI provides the project entry point for creating and working with BindAI applications. Create a new project:

bindai new my-ai-app

Enter the project:

cd my-ai-app

The generated project provides a starting structure for building a BindAI application. A project can contain application components such as:

my-ai-app/
├── agents/
├── tools/
├── workflows/
├── knowledge/
├── memory/
├── templates/
├── tests/
├── main.py
├── bindai.toml
└── .env.example

The exact generated contents may evolve as the BindAI project scaffold develops.

Configure Environment Variables

Most hosted AI providers require an API key. If the generated project includes an example environment file, create your local environment file.

Windows PowerShell

Copy-Item .env.example .env

macOS / Linux

cp .env.example .env

Open .env and configure the credentials required by your selected provider. For OpenAI:

OPENAI_API_KEY=your_api_key_here

For Anthropic:

ANTHROPIC_API_KEY=your_api_key_here

For Google Gemini:

GEMINI_API_KEY=your_api_key_here

For Groq:

GROQ_API_KEY=your_api_key_here

For OpenRouter:

OPENROUTER_API_KEY=your_api_key_here

Ollama can be used with a local model service and does not normally require a hosted API key.

Never commit API keys or other secrets to source control.

Run the Project

From inside the generated project, run:

bindai run

This starts the BindAI application through the CLI. The exact application output depends on the generated project and its configuration. If the application requires provider credentials, make sure the appropriate environment variables are configured before running it.

Verify Your Installation

If you encounter an installation or configuration problem, run:

bindai doctor

You can also verify the installed CLI version:

bindai version

Understanding the Project

A BindAI project can be organized around several major components.

`agents/`

Contains agent definitions. Agents are responsible for interacting with language models and coordinating AI execution. Agents can work with:

Prompts and instructions
Tools
Memory
Knowledge
Retrieval
Provider integrations
Execution configuration
Other agents

`tools/`

Contains reusable tools that agents can execute. Tools can represent:

Python functions
Application services
External APIs
Database operations
Search functionality
External integrations
MCP-backed tools

BindAI provides a tool registry and execution system for managing these capabilities.

`workflows/`

Contains workflow definitions. BindAI workflows support execution patterns such as:

Sequential execution
Conditional branching
Loops
Parallel execution
Retries
Timeouts
Scheduling
Human approval
Human tasks

`knowledge/`

Contains knowledge-related application resources. BindAI’s knowledge system supports capabilities such as:

Document ingestion
Parsing
Chunking
Embeddings
Metadata
Semantic retrieval
BM25 retrieval
Hybrid retrieval
Filtering
Reranking
Conversational retrieval

Knowledge can be connected to agents so retrieved information can be used as context during execution.

`memory/`

Contains memory-related application resources. BindAI supports multiple memory implementations, including:

In-memory memory
SQLite
PostgreSQL
Vector memory
Pinecone
Chroma
Conversation memory
Custom memory providers

`templates/`

Contains reusable workflow or application templates. Templates provide starting points for common BindAI execution patterns.

`tests/`

Contains application tests. Testing is an important part of developing reliable BindAI applications.

`main.py`

The application entry point. The exact contents depend on the project generated and the application being built.

`bindai.toml`

Project-level configuration. Use this file for BindAI project configuration supported by the application and CLI. Configuration options may evolve as the project architecture develops.

Creating an Agent

Agents are the central abstraction for building AI applications with BindAI. A basic agent can be created using the BindAI agent API. For example:

from bindai import Agent

agent = Agent.builder().build()

The agent can then be configured with the components required by your application, such as a provider, instructions, tools, memory, or knowledge. A typical agent configuration can include:

from bindai import Agent

agent = (
    Agent.builder().model("openai:gpt-4.1").instructions("You are a helpful AI assistant.").build()
)

The model identifier should match a model available through the selected provider.

Provider and model availability can change independently of BindAI. Check the provider documentation when selecting a model.

Running an Agent

Once an agent has been configured, it can be executed with an input message. For example:

result = agent.run("Explain what BindAI is.")

print(result.output)

The returned result contains the output produced by the agent execution. Agents can also be integrated into larger workflows and applications.

Adding Tools

Tools allow agents to perform actions instead of only generating text. A tool can be implemented as a Python function and exposed through BindAI’s tool system. For example:

from bindai import tool


@tool
def add(a: int, b: int) -> int:
    return a + b

The tool can then be provided to an agent through the agent’s tool configuration. For example:

agent = (
    Agent.builder()
    .model("openai:gpt-4.1")
    .instructions("You are a helpful assistant.")
    .tool(add)
    .build()
)

The agent can then use the registered tool when the model determines that the tool is appropriate.

Changing Providers

BindAI uses a provider abstraction so applications can work with different model providers. For example, an application can use an OpenAI model:

.model("openai:gpt-4.1")

An Anthropic model:

.model("anthropic:claude-sonnet-4")

An Ollama model:

.model("ollama:llama3")

Or an OpenRouter model:

.model("openrouter:your-model")

Other currently supported providers include Google Gemini and Groq. The exact model identifier depends on the provider and model you want to use.

Adding Memory

Agents can use memory to retain information across interactions. Memory is implemented through provider abstractions, allowing different storage backends to be used without coupling the agent to one database. Current memory backends include:

In-memory
SQLite
PostgreSQL
Pinecone
Chroma
Vector memory

Conversation memory can also be used to maintain conversational context.

Adding Knowledge

Knowledge allows agents to work with information outside the model’s built-in knowledge. A typical knowledge pipeline can involve:

Documents
   │
   ▼
Ingestion
   │
   ▼
Parsing
   │
   ▼
Chunking
   │
   ▼
Embeddings
   │
   ▼
Storage / Retrieval
   │
   ▼
Search
   │
   ▼
Reranking
   │
   ▼
Agent Context

BindAI supports vector, BM25, and hybrid retrieval strategies. This provides the foundation for Retrieval-Augmented Generation (RAG) applications.

Using Workflows

When an application requires multiple execution steps, workflows can coordinate the process. A workflow can combine:

Agents
Tools
Conditions
Loops
Parallel execution
Retries
Timeouts
Scheduling
Human tasks

For example:

Start
  │
  ▼
Agent
  │
  ▼
Condition
 ┌┴───────────┐
 ▼            ▼
Tool         Agent
 │            │
 └──────┬─────┘
        ▼
      Result

Workflows are useful when an application requires predictable multi-step execution instead of a single agent call.

Connecting External Services

BindAI also provides a Connections abstraction for external services. Current integrations include:

Webhooks
GitHub
Slack
Notion
Jira
Discord
Resend
Vercel
Netlify

Connections can be managed through the BindAI Connections package and integrated into applications and workflows.

Using MCP Tools

BindAI includes Model Context Protocol support. MCP allows BindAI applications to discover and call tools exposed by compatible MCP services. The current MCP implementation supports:

MCP client connections
Tool discovery
Tool calling
MCP tools exposed through the BindAI tool system

This provides another way for agents to access external capabilities.

Running Tests

Run the project’s tests with:

pytest

For source development, BindAI’s repository uses a multi-package uv workspace. From the repository root:

uv sync

Then run the relevant test suite.

Useful CLI Commands

Create a project:

bindai new my-app

Run the application:

bindai run

Inspect the project:

bindai inspect

Check the environment:

bindai doctor

Display the installed version:

bindai version

What You’ve Learned

You have now seen the basic BindAI development workflow:

Created a BindAI project
Configured a model provider
Started a BindAI application
Learned the project structure
Created an agent
Added a tool
Learned how providers can be changed
Learned how memory works
Learned how knowledge and RAG fit into an application
Learned how workflows coordinate execution
Learned about external Connections
Learned about MCP tool integration

You are now ready to explore the individual BindAI components in more depth.

Next Steps

Continue with:

For the overall implementation status, see the ROADMAP.

​Quick Start

​Prerequisites

​Create a New Project

​Configure Environment Variables

​Windows PowerShell

​macOS / Linux

​Run the Project

​Verify Your Installation

​Understanding the Project

​agents/

​tools/

​workflows/

​knowledge/

​memory/

​templates/

​tests/

​main.py

​bindai.toml

​Creating an Agent

​Running an Agent

​Adding Tools

​Changing Providers

​Adding Memory

​Adding Knowledge

​Using Workflows

​Connecting External Services

​Using MCP Tools

​Running Tests

​Useful CLI Commands

​What You’ve Learned

​Next Steps